LibGDX is a gaming framework which works on the JVM. Using it, you can create a game for mobile, desktop and web platform.

Kotlin is a language compatible with the JVM (Java Virtual Machine) platform. It’s like Java but shorter.

LibGDX-addons is a set of addons, gradle plugins, …, to ease the development of games using libGDX and Kotlin. Get ride of all boilerplate to dive directly into the code of your game.

Important
 This documentation is open source. You can correct it, updated it or add content of you want to. Just Fork it and submit a merge request of your update. Thanks!

Getting started

LibGDX use gradle as a build system. You can use the official setup app to create your game. Instead LibGDX-addons propose a gradle plugin to take care of all gradle setup, for all platform (Currently supported: Desktop and Android) so you don’t have to manage it or update your gradle script.

Setup your game

Create your first game by using IntelliJ. Click in File > New Project

create game 01

Pick Gradle then tick Kotlin DSL build script, choose Kotlin/JVM and go to the next screen by clicking Next.

create game 02

Fill the information asked and click Next until IntelliJ create your project.

Open the file build.gradle.kts and paste this configuration into. It adds necessary repositories for dependencies and add the gradle libgdx plugin.

build.gradle.kts
buildscript {
    dependencies {
        classpath("com.github.dwursteisen.libgdx-addons:libgdx-gradle-plugin:5b04dc1")
    }

    repositories {
        mavenCentral()
        google()
        maven { url = uri("https://oss.sonatype.org/content/repositories/releases/") }
        maven { url = uri("https://oss.sonatype.org/content/repositories/snapshots/") }
        maven { url = uri("https://jitpack.io") }
    }
}

apply(plugin = "libgdx")

Run the command gradlew build: it will download gradle if needed and download all dependencies and create the minimal setup. Once done, it might be long depending of your Internet connection, refresh the project in IntelliJ.

create game 02b
Figure 1. Your project when everything is ready

Run your game

Your game project is now ready! A new Run Configuration just appear in your IntelliJ. Click on Add Configuration and check Application run configurations. You will see a run configuration added in IntelliJ to run your game.

create game 03
Note
 The first run will crash! Because you need to create your first game class. See bellow for more information.

Draw your first texture

Grab an image and copy it into the assets directory of the core module. You can find free image / sprite sheet on the OpenGameArt.org.

Run the command ./gradlew build, the command will generate a new class Assets that will contains all of your assets name.

Note
 The use of the Assets object is not mandatory. But if your rename one of your assets, it’s practical to have a compilation error instead of your game crashing.

Create your game into the core directory and use it in MainClass.kt.

MyGame.kt
class MyGame : Game() {

    private lateinit var texture: Texture

    private lateinit var batch: SpriteBatch

    override fun create() {
        texture = Texture(Assets.assets_dungeon_sheet_png)
        batch = SpriteBatch()
    }

    override fun render() {
        batch.begin()
        batch.draw(texture, 0f, 0f)
        batch.end()
    }
}
MainClass.kt
object MainClass {
    @JvmStatic
    fun main(args: Array<String>) {
        LwjglApplication(MyGame(), LwjglApplicationConfiguration().apply {
            width = 600
            height = 600
        })
    }
}

If you run your game, the texture will be displayed on the screen.

create game 04

Increase your feedback loop

It’s important to have a quick feedback loop while developing a game. For example, what’s the point of restarting your game when you just updated a texture from your game?

To enable this feature, you need to add a dependency to the libgdx core-addons.

Add this into your build.gradle.kts then refresh the project in your IDE:

build.gradle.kts
project(":core") {
    dependencies {
        implementation("com.github.dwursteisen.libgdx-addons:core-addons:5b04dc1")
    }
}

You can now update your game to use the asset manager of libgdx with RefreshableTexture.

MyGame.kt
class MyGame : Game() {

    private val assetManager: AssetManager = AssetManager()

    private lateinit var batch: SpriteBatch

    override fun create() {
        // (1)
        assetManager.setLoader(Texture::class.java, RefreshableTextureLoader(InternalFileHandleResolver()))
        assetManager.load(Assets.assets_dungeon_sheet_png, Texture::class.java)
        // (2)
        assetManager.finishLoading()
        batch = SpriteBatch()
    }

    override fun render() {
        // (3)
        Gdx.gl.glClearColor(0f, 0f, 0f, 1f)
        Gdx.gl.glClear(GL20.GL_COLOR_BUFFER_BIT)

        // (4)
        val texture: Texture = assetManager[Assets.assets_dungeon_sheet_png]
        batch.begin()
        batch.draw(texture, 0f, 0f)
        batch.end()
    }
}

  1. Replace the default Texture Loader with the RefreshableTexture Loader;

  2. Force to load all assets before rendering the game;

  3. Clear the screen;

  4. Getting the texture from the asset manager.

Run your game and while the game is running, apply a modification on the texture file. As soon as you save the file, the texture will be updated in your game.

create game 05
Note
 The asset manager is not mandatory. But by using it, you can use the RefreshableTexture for the desktop version of your game and the default texture loader for your android game without having to change your whole code base.

Setup a entity engine

Tip
 WIP

React to events

Tip
 WIP

Create a state machine

Tip
 WIP

Package your game for Desktop

Tip
 WIP

Package your game for Android

Tip
 WIP

LibGDX Libraries

Tip
 WIP

LibGDX Gradle plugins

Tip
 WIP

Assets Gradle Plugin

When developing a game, you need to manage resources. Time to time you need to rename a file. In such case, you need to track every time you reference the file name by a string.

val sprite = load("mySprite.png")

To avoid to search for every place you’re loading the file using a String, the assets plugin can generate an Assets object that will hold all references to all your assets.

Assets.kt
object Assets {
    val mySprite: String = "mySprite.png"
}

If you rename an asset, then the class will be re-generated and you game will not compile! Which is way better than compile and crash later.

Tip
 It’s better to have a game that doesn’t compile than a game that compile, run and crash only when the game will load the missing asset.

Configuration

build.gradle.kts
import com.github.dwursteisen.libgdx.assets.AssetsPlugin
import com.github.dwursteisen.libgdx.assets.AssetsPluginExtension

plugins {
    id("assets")
}
apply<AssetsPlugin>()

configure<AssetsPluginExtension> {
    assetsClass.set(project.buildDir.resolve("generated/NewAssets.kt"))
}

You can configure the plugin using several options:

open class AssetsPluginExtension(project: Project) {
    /**
     * Which directory should be scan so all files will be referenced in the Assets object.
     */
    val assetsDirectory = project.createProperty<FileCollection>()
        .value(project.files("src/main/assets"))

    /**
     * Which class (aka Assets object) will reference all assets name.
     */
    val assetsClass = project.createProperty<File>()
        .value(project.buildDir.resolve("generated/Assets.kt"))
}